home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / pascal / pibasy47.zip / AAREADME.1ST next >
Text File  |  1988-06-03  |  11KB  |  286 lines
  1. INTRODUCTION
  2. ============
  3.  
  4. PIBASYNC.ARC is an archive file which contains a set of routines for
  5. implementing fully-buffered asynchronous serial port I/O from Turbo Pascal
  6. on the IBM PC and compatibles.  The routines have been extracted
  7. from my PibTerm v4.1 program and converted for used with Turbo Pascal v4.0.
  8.  
  9. Features of PibAsync:
  10.  
  11.    -- Both input and output buffering for the serial port, resulting
  12.       in improved performance especially under multitaskers
  13.    -- Buffer sizes are user-definable up to 32K bytes each for
  14.       the input and output ring buffers
  15.    -- Speeds up through 57600 baud
  16.    -- Support for Com1: through Com4: (one port at a time)
  17.    -- The ability to re-define port addresses, interrupt numbers,
  18.       and IRQ lines for non-standard ports
  19.    -- Optional XON/XOFF handling at the interrupt level
  20.    -- Optional CTS/RTS handling at the interrupt level
  21.    -- Optional DSR/DTR handling at the interrupt level
  22.    -- Machine code (via INLINE) provides respectable speed for
  23.       the basic functions
  24.  
  25. Limitation:
  26.  
  27.    -- Only one serial port is supported at a time.  It would be
  28.       an interesting project for someone to provide multiple
  29.       simultaneous port access.
  30.  
  31.  
  32. ARCHIVE CONTENTS
  33. ================
  34.  
  35. The following 19 files should be present in PIBASYNC.ARC:
  36.  
  37.      AAREADME.1ST  --- What you're reading now
  38.      ASCII.GLO     --- Some Ascii character set definitions
  39.      ASYINT.ASM    --- ASM source for asynchronous handler
  40.      ASYNCREC.ASM  --- ASM source for receive-a-character routine
  41.      ASYNCSEN.ASM  --- ASM source for send-a-character (buffered) routine
  42.      ASYSENOW.ASM  --- ASM source for send-a-character (unbuffered) routine
  43.      DUMBTRM.PAS   --- Sample dumb terminal emulator
  44.      FDELAY.ASM    --- ASM source for 1 ms delay calculation
  45.      FIXBRACK.PAS  --- Routine for neatening .OBJ files produced
  46.                        by the INLINE assembler.
  47.      GLOBTYPE.GLO  --- Global declarations for non-async-related variables
  48.                        needed by async code
  49.      GLOBTYPE.PAS  --- Main program for unit GLOBTYPE.TPU.
  50.      MAKEDUMB.BAT  --- Batch file which calls TPC to compile DUMBTRM.PAS
  51.      PIBASYN1.MOD  --- Asynchronous I/O routines, part 1
  52.      PIBASYN2.MOD  --- Asynchronous I/O routines, part 2
  53.      PIBASYN3.MOD  --- Asynchronous I/O routines, part 3
  54.      PIBASYNC.GLO  --- Global declarations for async-related variables
  55.      PIBASYNC.PAS  --- Main program for PIBASYNC.TPU.
  56.      PIBTIMER.PAS  --- Time of day interface routines
  57.      TIMEREC.ASM   --- ASM source for receiving character with delay
  58.  
  59. The .ASM files can be assembled with Dave Baldwin's program INLINE.COM,
  60. which converts the assembler source to Turbo Pascal INLINE statements.
  61. (You will need at least v2.11 of INLINE.COM to correctly assemble this code.)
  62. The PIBASYN*.MOD files already contain the processed assembler source,
  63. so you do not need to run INLINE on the .ASM files unless you want to alter
  64. them.
  65.  
  66.  
  67. COMPATIBILITY WITH PREVIOUS VERSIONS
  68. ====================================
  69.  
  70. The calling sequences of these revised routines are largely compatible
  71. with those previously available as part of earlier versions of
  72. PibTerm.  If you used those earlier routines, you should be able
  73. to convert to these (with a resulting increase in efficiency) with
  74. very little trouble.  The major important changes are that the
  75. routines Async_Init and Async_Close now take arguments.
  76.  
  77. In the conversion to Turbo Pascal v4.0, I took advantage of the
  78. new availability of the WORD type to add 57600 baud.
  79. Hence, routines in which the baud rate is passed as an argument
  80. (Async_Open, Async_Reset) now have the baud rate as a WORD
  81. instead of an INTEGER.
  82.  
  83.  
  84. DOCUMENTATION
  85. =============
  86.  
  87. See the documentation block headers for individual routines in PIBASYN*.MOD
  88. for details on the calling sequences and usage of the routines.
  89.  
  90.  
  91. SAMPLE PROGRAM
  92. ==============
  93.  
  94. The DUMBTRM.PAS routine demonstrates how to use the PibAsync routines to
  95. build a dumb terminal emulation program.
  96.  
  97.  
  98. USE OF THE ROUTINES
  99. ===================
  100.  
  101. You may use these routines for any NON-COMMERCIAL purpose whatsoever.
  102. If you change these routines, you MUST make the revised source
  103. available.  Many individuals used the code from previous versions
  104. of PibTerm and incorporated interesting changes in the async routines,
  105. but did NOT make the resulting changes available in source form
  106. so that all of us could benefit.  I take a dim view of that;  I have
  107. made this source code available so that others can learn from what
  108. I have done (and correct my mistakes).  I expect you to provide
  109. the same courtesy in return.
  110.  
  111.  
  112. SUPPORT
  113. =======
  114.  
  115. Please realize that these routines are not a commercial effort and that
  116. I simply cannot afford the time or money to individually support users.
  117. I WILL NOT return phone calls about these routines, and I WILL NOT
  118. fix your code for you.
  119.  
  120. There are a number of commercial packages of asynchronous routines
  121. available for Turbo Pascal.  If you need a package for commercial
  122. development, you should consider one of them.
  123.  
  124. You may send messages to me as indicated below, if you wish.  I will not
  125. necessarily answer all queries individually, however.
  126.  
  127.  
  128. ADDRESSES FOR ELECTRONIC LETTER BOMBS
  129. =====================================
  130.  
  131. You may leave me messages on the following BBSs:
  132.  
  133.       Gene Plantz's BBS                (312) 882 4145
  134.       Northwestern Univerity OPUS BBS  (312) 491 3892
  135.  
  136. Gene's BBS is registration only ($25 a year) and well worth it.
  137. The Northwestern University BBS is run by my colleague Roger Safian.
  138. You can use the OPUS/FIDONET remote mail/networking facility to send me
  139. messages from another OPUS local to your dialing area.  The net address
  140. of Roger's OPUS BBS system is 115/419.
  141.  
  142. For both BBS systems, my user name is PHILIP BURNS.
  143.  
  144. CompuServe users can reach me at:
  145.  
  146.        72437,62
  147.  
  148. University users can reach me at:
  149.  
  150.       PIB@NUACC.BITNET         (BITNET)
  151.       PIB@NUACC.ACNS.NWU.EDU   (ARPANET)
  152.  
  153. PLEASE, no voice calls!  I WILL NOT RETURN any long distance phone
  154. calls about PibAsync.  I can't afford to.
  155.  
  156. -- Thanks,
  157.    Phil Burns   03/21/88
  158.  
  159.  
  160. Changes for v4.1 of these routines:
  161. ===================================
  162.  
  163. I corrected delay loops by avoiding the use of a Turbo run-time library
  164. variable.  This 1-millesecond delay variable changed meaning at
  165. v3.02 of Turbo, causing the various delay loops in PibAsync to
  166. run incorrectly (for too short a time).  I now calculate and use
  167. my own delay loop value, independent of Turbo's.
  168.  
  169. -- Phil Burns   12/27/86
  170.  
  171.  
  172. Changes for v4.2 of these routines:
  173. ===================================
  174.  
  175. A couple of routines incorrectly left a word on the stack that should
  176. have been popped in cases when the circular buffers were full.  Those
  177. problems have been fixed in this version.
  178.  
  179. -- Phil Burns   01/24/86
  180.  
  181.  
  182. Changes for v4.3 of these routines:
  183. ===================================
  184.  
  185. The send routine incorrectly tested for the wrong circular buffer pointer
  186. when the output buffer was full.  This resulted in output buffer overruns
  187. with lots of attendant nasty problems.
  188.  
  189. -- Phil Burns   03/25/87
  190.  
  191.  
  192. Changes for v4.4 of these routines:
  193. ===================================
  194.  
  195. The code to setup mark and space parity was incorrect.  This has been
  196. corrected in this version.
  197.  
  198. -- Phil Burns   07/20/87
  199.  
  200.  
  201. Changes for v4.5 of these routines:
  202. ===================================
  203.  
  204. I have converted the async routines to a UNIT for v4.0 of Turbo Pascal.
  205.  
  206. To use the async routines, just do a
  207.  
  208.    USES
  209.       DOS, PIBASYNC;
  210.  
  211. You don't need to include the code at all.  Just compile PIBASYNC.PAS
  212. and place the resulting PIBASYNC.TPU in your unit include subdirectory.
  213.  
  214. 38400 baud is now supported.
  215.  
  216. I've altered the character send routine to wait for a slot before
  217. overwriting an existing buffer character when the output buffer is full,
  218. rather than overwriting and then waiting.
  219.  
  220. The code to support serial ports 3 and 4 has been corrected.  Make sure
  221. to call Async_Setup_Port before using ports 3 and 4, or when you're using
  222. a non-standard port address on ports 1 and 2.  Async_Setup_Port will
  223. now insert the port address you specify at the proper offset from
  224. $0:$400, the address of the 8250.  If you set port address = -1, the
  225. default port address is used; if you set irq = -1, then the default
  226. IRQ is used.  The new function Async_Port_Address_Given can be used to
  227. check if the RS232 base address is installed in memory or not.
  228.  
  229. The preprocessor symbol MTASK should be defined if you are using
  230. these routines in conjunction with the PIBMDOS routines for interfacing
  231. to multitaskers.
  232.  
  233. The routines DOS_Set_Intrpt and DOS_Get_Intrpt have been removed and
  234. replaced by the standard TP4 routines GetIntVec and SetIntVec, respectively.
  235.  
  236. The batch file MAKEDUMB.BAT makes the DUMBTRM.EXE sample program
  237. using the command line compiler (TPC.EXE).
  238.  
  239. -- Phil Burns   11/11/87
  240.  
  241.  
  242. Changes for v4.6 of these routines:
  243. ===================================
  244.  
  245. You can now redefine the interrupt numbers used for each serial port.
  246. The calling sequence of Async_Setup_Port has changed as a result.
  247.  
  248. There are new routines for sending a character immediately and bypassing
  249. the current serial port output buffer (Async_Send_Now), for draining
  250. the output buffer (Async_Drain_Output_Buffer), and for waiting for
  251. the serial port to quiesce (Async_Wait_For_Quiet).
  252.  
  253. -- Phil Burns    02/21/88
  254.  
  255.  
  256. Changes for v4.7 of these routines:
  257. ===================================
  258.  
  259. 57600 baud is now supported.
  260.  
  261. IRQ levels 8 through 15 are now (theoretically) supported for AT and
  262. PS/2 machines.
  263.  
  264. PibAsync now honors both ends of DSR/DTR and CTS/RTS hardware flow
  265. control.  Previously, PibAsync only checked the CTS and DSR lines
  266. when sending characters.  Now PibAsync will use the corresponding RTS
  267. and DTR lines when receiving characters as well.  This is required
  268. when using these routines at high speeds or with the current crop of
  269. 9600/19200 bps modems.
  270.  
  271. When opening and closing a serial port, PibAsync tries harder to
  272. save and restore the old serial port characteristics.  This makes
  273. it easier to use these routines when writing a module to be invoked
  274. from another communications programs, as when providing an external
  275. file transfer protocol driver.
  276.  
  277. I have also added an optional "noise rejection" feature to the
  278. serial interrupt code.  This provides a mechanism for rejecting
  279. defective characters immediately upon arrival at the serial port,
  280. which can be useful for coping with spurious line noise characters.
  281. Reasons for rejection include framing errors, parity errors, or
  282. line breaks.  "Bad" characters are replaced with a user-selectable
  283. character (NUL by default).  The routine "Async_Set_Rejection" provides
  284. for activating and deactivating the rejection mechanism.
  285.  
  286. -- Phil Burns    05/23/88